.\" Copyright (C) 2004-2012  Dmitry V. Levin <ldv@altlinux.org>
.\" 
.\" Documentation for the hasher-priv program.
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later

[NAME]
\fBhasher-priv\fR \- privileged helper for the hasher project

[FILES]
.TP
.I /etc/hasher\-priv/system
systemwide config file
.TP
\fI/etc/hasher\-priv/user.d/\fBUSER\fR
per-user config files
.TP
\fI/etc/hasher\-priv/user.d/\fBUSER\fI:\fBNUMBER\fR
per-user per-number subconfig files

[ENVIRONMENT]
The following environment variables are processed by
.BR hasher\-priv:
.TP
.B requested_mountpoints
Defines a comma-separated list of mount points which shall be mounted
in
.B chrootuid1
and
.B chrootuid2
operation modes, if allowed by
.B allowed_devices
or
.B allowed_mountpoints
configuration options.
.TP
.B wlimit_time_elapsed
Define total execution time limit, in seconds.
If
.B wlimit_time_elapsed
config parameter is also set, then minimal value will be used.
.TP
.B wlimit_time_idle
Define idle time limit, in seconds.
Idle time is a period when child process produces no output.
If
.B wlimit_time_idle
config parameter is also set, then minimal value will be used.
.TP
.B wlimit_bytes_written
Define limit of output generated by child process, in bytes.
If
.B wlimit_bytes_written
config parameter is also set, then minimal value will be used.
.TP
.B use_pty
This boolean specifies whether stdin, stdout and stderr of child process
will be redirected to controlling pseudoterminal created by
.BR hasher\-priv.
By default, stdin remains unchanged unless it references to terminal
device, and stdout with stderr are redirected to pipe created by
.BR hasher\-priv.
.TP
.B share_ipc
This boolean specifies whether IPC namespace inside chroot should be shared
with host IPC namespace.
By default, IPC namespace inside chroot is isolated from host IPC namespace if
.BR unshare (CLONE_NEWIPC)
syscall is supported by kernel.
.TP
.B share_network
This boolean specifies whether network inside chroot should be shared
with host network.
By default, network inside chroot is isolated from host network if
.BR unshare (CLONE_NEWNET)
syscall is supported by kernel.
.TP
.B share_uts
This boolean specifies whether UTS namespace inside chroot should be shared
with host UTS namespace.
By default, UTS namespace inside chroot is isolated from host UTS namespace if
.BR unshare (CLONE_NEWUTS)
syscall is supported by kernel.
.TP
.B TERM
This variable will be passed to child process if
.B use_pty
is set to true.

[SECURITY]
Following operation modes are not security sensitive:
.TP
.BR getugid1 ", " getugid2
Query pseudouser identifiers.
.PP
Following operation modes have minimal security implications:
.TP
.B killuid
Kill all processes running by pseudousers.
.PP
Following operation modes have high security implications:
.TP
.BR chrootuid1 ", " chrootuid2
Execute program in build chroot with credentials of pseudouser.

This operation also unshares mount namespace and
mounts all mount points that are specified by
.B requested_mountpoints
environment variable and allowed by
.B allowed_devices
or
.B allowed_mountpoints
configuration options.
Note that some of file systems are more security sensitive than others.
For example,
.I proc
and
.I sysfs
virtual file systems provide access to various
system resources which could be abused by pseudousers,
.I devpts
virtual file system provides access to all pty device files
(unless mounted with
.I newinstance
mount option) which also could be abused by pseudousers if these files
have inappropriate permissions.

This operation also creates essential device files available for all users:
.IR null ,
.IR zero ,
.IR full ,
and
.IR urandom .
Pseudousers may abuse
.I urandom
to cause host system randomness starvation.

If
.I /dev/pts
is mounted, this operation also creates terminal device files:
.I tty
(current tty device) and
.I ptmx
(PTY master multiplex).

.PP
All risky operation modes are not enabled by default.  They could be
explicitly enabled in
.B hasher\-priv
configuration.

[SEE ALSO]
.BR unshare (2),
.BR hasher\-priv.conf (5),
.BR hasher (7),
.BR hasher\-useradd (8).
